<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Qi Keyword Parser Directive</title>
<link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Spirit Repository 0.2">
<link rel="up" href="../directives.html" title="Qi Parser Directives">
<link rel="prev" href="distinct.html" title="Qi Distinct Parser Directive">
<link rel="next" href="seek.html" title="Qi Seek Parser Directive">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="distinct.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../directives.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="seek.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="spirit_repository.qi_components.directives.kwd"></a><a class="link" href="kwd.html" title="Qi Keyword Parser Directive">Qi
        Keyword Parser Directive </a>
</h4></div></div></div>
<h6>
<a name="spirit_repository.qi_components.directives.kwd.h0"></a>
          <span class="phrase"><a name="spirit_repository.qi_components.directives.kwd.description"></a></span><a class="link" href="kwd.html#spirit_repository.qi_components.directives.kwd.description">Description</a>
        </h6>
<p>
          The <code class="computeroutput"><span class="identifier">kwd</span><span class="special">[]</span></code>,
          <code class="computeroutput"><span class="identifier">dkwd</span><span class="special">[]</span></code>
          and <code class="computeroutput"><span class="identifier">ikwd</span><span class="special">[]</span></code>,
          <code class="computeroutput"><span class="identifier">idkwd</span><span class="special">[]</span></code>
          provide a powerful and flexible mechanism for parsing keyword based input.
          It works in conjunction with the / operator to create an effective keyword
          parsing loop. The keyword parsing loop doesn't require the keywords to
          appear in a defined order in the input but also provides the possibility
          to check how many times a keyword appears in the input.
        </p>
<p>
          The kwd directive will parse the keywords respecting case sensitivity whereas
          the ikwd direcive is case insensitive. You can mix the kwd and ikwd directives
          inside a set of keywords, but be aware that this has a small overhead.
          It should be preferred not to mix the kwd and ikwd directives.
        </p>
<p>
          The dkwd and idkwd provide a mechanism to pase distinct keywords. These
          directives require that the skipper successeds parsing input right after
          the keyword part.
        </p>
<p>
          dkwd("keyword1")<span class="emphasis"><em>='&gt;&gt;int_</em></span>
        </p>
<p>
          is equivalent to:
        </p>
<p>
          lit("keyword1") &gt;&gt; skipper+ &gt;&gt; '=' &gt;&gt; int_
        </p>
<p>
          All the keyword directives can be mixed inside a keyword list.
        </p>
<p>
          The kwd directive is very similar to the repeat directive in that it enables
          to enforce keyword occurrence constraints but also provides very interesting
          speed improvement over the pure EBNF syntax or the Nabialek-Trick.
        </p>
<h6>
<a name="spirit_repository.qi_components.directives.kwd.h1"></a>
          <span class="phrase"><a name="spirit_repository.qi_components.directives.kwd.header"></a></span><a class="link" href="kwd.html#spirit_repository.qi_components.directives.kwd.header">Header</a>
        </h6>
<pre class="programlisting"><span class="comment">// forwards to &lt;boost/spirit/repository/home/qi/directive/kwd.hpp&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">repository</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">qi_kwd</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
</pre>
<h6>
<a name="spirit_repository.qi_components.directives.kwd.h2"></a>
          <span class="phrase"><a name="spirit_repository.qi_components.directives.kwd.synopsis"></a></span><a class="link" href="kwd.html#spirit_repository.qi_components.directives.kwd.synopsis">Synopsis</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                  <p>
                    Expression
                  </p>
                </th>
<th>
                  <p>
                    Semantics
                  </p>
                </th>
</tr></thead>
<tbody>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">kwd</span><span class="special">(</span><span class="identifier">keyword</span><span class="special">)[</span><span class="identifier">subject</span><span class="special">]</span></code>
                  </p>
                </td>
<td>
                  <p>
                    Parse ( <code class="computeroutput"><span class="string">"keyword"</span></code>
                    &gt; <code class="computeroutput"><span class="identifier">subject</span></code>)
                    zero or more times.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">kwd</span><span class="special">(</span><span class="identifier">keyword</span><span class="special">,</span><span class="identifier">n</span><span class="special">)[</span><span class="identifier">subject</span><span class="special">]</span></code>
                  </p>
                </td>
<td>
                  <p>
                    Parse ( <code class="computeroutput"><span class="string">"keyword"</span></code>
                    &gt; <code class="computeroutput"><span class="identifier">subject</span></code>)
                    exactly <code class="computeroutput"><span class="identifier">n</span></code> times.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">kwd</span><span class="special">(</span><span class="identifier">keyword</span><span class="special">,</span><span class="identifier">min</span><span class="special">,</span>
                    <span class="identifier">max</span><span class="special">)[</span><span class="identifier">subject</span><span class="special">]</span></code>
                  </p>
                </td>
<td>
                  <p>
                    Parse ( <code class="computeroutput"><span class="string">"keyword"</span></code>
                    &gt; <code class="computeroutput"><span class="identifier">subject</span></code>)
                    at least <code class="computeroutput"><span class="identifier">min</span></code>
                    times and at most <code class="computeroutput"><span class="identifier">max</span></code>
                    times.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">kwd</span><span class="special">(</span><span class="identifier">keyword</span><span class="special">,</span><span class="identifier">min</span><span class="special">,</span>
                    <span class="identifier">inf</span><span class="special">)[</span><span class="identifier">subject</span><span class="special">]</span></code>
                  </p>
                </td>
<td>
                  <p>
                    Parse ( <code class="computeroutput"><span class="string">"keyword"</span></code>
                    &gt; <code class="computeroutput"><span class="identifier">subject</span></code>)
                    at least <code class="computeroutput"><span class="identifier">min</span></code>
                    or more.
                  </p>
                </td>
</tr>
</tbody>
</table></div>
<p>
          For non case sensitive keywords use the ikwd directive. If distinct keyword
          parsing is required, use the dkwd and idkwd directive instead.
        </p>
<h6>
<a name="spirit_repository.qi_components.directives.kwd.h3"></a>
          <span class="phrase"><a name="spirit_repository.qi_components.directives.kwd.parameters"></a></span><a class="link" href="kwd.html#spirit_repository.qi_components.directives.kwd.parameters">Parameters</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                  <p>
                    Parameter
                  </p>
                </th>
<th>
                  <p>
                    Description
                  </p>
                </th>
</tr></thead>
<tbody>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">keyword</span></code>
                  </p>
                </td>
<td>
                  <p>
                    The parser for the opening (the prefix).
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">subject</span></code>
                  </p>
                </td>
<td>
                  <p>
                    The parser for the input sequence following the keyword part.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">n</span></code>
                  </p>
                </td>
<td>
                  <p>
                    Int representing the exact number of times the keyword must be
                    repeated.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">min</span></code>
                  </p>
                </td>
<td>
                  <p>
                    Int representing the minimum number of times the keyword must
                    be repeated.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">max</span></code>
                  </p>
                </td>
<td>
                  <p>
                    Int representing the maximum number of times the keyword must
                    be repeated.
                  </p>
                </td>
</tr>
</tbody>
</table></div>
<p>
          The keyword as well as the subject parameters can be any valid spirit parser.
          The parameter n, min and max are integer constants.
        </p>
<h6>
<a name="spirit_repository.qi_components.directives.kwd.h4"></a>
          <span class="phrase"><a name="spirit_repository.qi_components.directives.kwd.attributes"></a></span><a class="link" href="kwd.html#spirit_repository.qi_components.directives.kwd.attributes">Attributes</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                  <p>
                    Expression
                  </p>
                </th>
<th>
                  <p>
                    Attribute
                  </p>
                </th>
</tr></thead>
<tbody>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">kwd</span><span class="special">(</span><span class="identifier">k1</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></code>
                  </p>
                </td>
<td>
                  <p>
</p>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="identifier">kwd</span><span class="special">(</span><span class="identifier">k1</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span> <span class="keyword">or</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="identifier">kwd</span><span class="special">(</span><span class="identifier">k1</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">Unused</span></pre>
<p>
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">kwd</span><span class="special">(</span><span class="identifier">k1</span><span class="special">,</span><span class="identifier">n</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></code>
                  </p>
                </td>
<td>
                  <p>
</p>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="identifier">kwd</span><span class="special">(</span><span class="identifier">k1</span><span class="special">,</span><span class="identifier">n</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span> <span class="keyword">or</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="identifier">kwd</span><span class="special">(</span><span class="identifier">k1</span><span class="special">,</span><span class="identifier">n</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">Unused</span></pre>
<p>
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">kwd</span><span class="special">(</span><span class="identifier">k1</span><span class="special">,</span><span class="identifier">min</span><span class="special">,</span>
                    <span class="identifier">max</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></code>
                  </p>
                </td>
<td>
                  <p>
</p>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="identifier">kwd</span><span class="special">(</span><span class="identifier">k1</span><span class="special">,</span><span class="identifier">min</span><span class="special">,</span> <span class="identifier">max</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span> <span class="keyword">or</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="identifier">kwd</span><span class="special">(</span><span class="identifier">k1</span><span class="special">,</span><span class="identifier">min</span><span class="special">,</span> <span class="identifier">max</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">Unused</span></pre>
<p>
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">kwd</span><span class="special">(</span><span class="identifier">k1</span><span class="special">,</span><span class="identifier">min</span><span class="special">,</span>
                    <span class="identifier">inf</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></code>
                  </p>
                </td>
<td>
                  <p>
</p>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="identifier">kwd</span><span class="special">(</span><span class="identifier">k1</span><span class="special">,</span><span class="identifier">min</span><span class="special">,</span> <span class="identifier">inf</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span> <span class="keyword">or</span> <span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;</span>
<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--&gt;</span> <span class="identifier">kwd</span><span class="special">(</span><span class="identifier">k1</span><span class="special">,</span><span class="identifier">min</span><span class="special">,</span> <span class="identifier">inf</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">Unused</span></pre>
<p>
                  </p>
                </td>
</tr>
</tbody>
</table></div>
<h6>
<a name="spirit_repository.qi_components.directives.kwd.h5"></a>
          <span class="phrase"><a name="spirit_repository.qi_components.directives.kwd.complexity"></a></span><a class="link" href="kwd.html#spirit_repository.qi_components.directives.kwd.complexity">Complexity</a>
        </h6>
<div class="blockquote"><blockquote class="blockquote">
<p>
            The overall complexity is defined by the complexity of its subject parser.
            The complexity of the keyword list construct <code class="computeroutput"><span class="identifier">kwd</span></code>
            itself is O(N), where N is the number of repetitions executed.
          </p>
<p>
            In the case where all the keywords are strings, the complexity of the
            keyword list itself determined by the complexity of the internal TST
            contents :
          </p>
<p>
            O(log n+k)
          </p>
<p>
            Where k is the length of the string to be searched in a TST with n strings.
          </p>
<p>
            When the keywords used are complex parsers, then the complexity is the
            sum of the sub parser complexities.
          </p>
</blockquote></div>
<h6>
<a name="spirit_repository.qi_components.directives.kwd.h6"></a>
          <span class="phrase"><a name="spirit_repository.qi_components.directives.kwd.example"></a></span><a class="link" href="kwd.html#spirit_repository.qi_components.directives.kwd.example">Example</a>
        </h6>
<p>
          Please refer to keyword_list.
        </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="distinct.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../directives.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="seek.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
